% -*-LaTeX-*-
% Converted automatically from troff to LaTeX
% by tr2latex (version 1.04, July 15, 1991)
% on Mon Oct 28 10:50:25 1991
% tr2latex was written by Kamal Al-Yahya at Stanford University
% (Kamal%Hanauma@SU-SCORE.ARPA)

\documentstyle[troffman,twoside]{article}
\begin{document}
%
% input file: pcal.man
%
% pcal.man - documentation for Pcal v4.3
%
\phead{PCAL}{4.3}{13 December 1991}{}{}

\shead{NAME}
pcal -- generate PostScript calendars

\shead{SYNOPSIS}
{\bf pcal}
[{\bf --e} $|$ {\bf --f} {\it cal\/}] [{\bf --o} {\it file\/}]
[{\bf --j} $|$ {\bf --J} ] [{\bf --l} $|$ {\bf --p}] [{\bf --m} $|$ {\bf--M}]
[{\bf --b} {\it day $|$ all\/}] [{\bf --g} {\it day $|$ all\/}]
[{\bf --O}] [{\bf --G}]\hfil\break
[{\bf --s} [{\it date\_shade}] [{\it /fill\_shade}]]
[{\bf --F} {\it day\/}] [{\bf --A} $|$ {\bf --E}]
[{\bf --t} {\it title\_font\/}]
[{\bf --d} {\it day\_font\/}]
[{\bf --n} {\it text\_font\/} [/{\it size\/}]]\hfil\break
[{\bf --L} {\it footer\_str\/}]
[{\bf --C} {\it footer\_str\/}]
[{\bf --R} {\it footer\_str\/}]
[{\bf --N} {\it notes\_str\/}]
[{\bf --D} {\it symbol\/}] [{\bf --U} {\it symbol\/}]
[{\bf --x} {\it xscale\/}] \hfil\break
[{\bf --y} {\it yscale\/}] [{\bf --X} {\it xtrans\/}]
[{\bf --Y} {\it ytrans\/}] [{\bf --I}] [{\bf --B}]
[{\bf --S} $|$ {\bf --k} $|$ {\bf --K}] [{\bf --w}]
[{\bf --h} $|$ {\bf --u} $|$ {\bf --v}]\hfil\break
[month] [year] [nmonths]

\shead{DESCRIPTION}
{\it Pcal} generates PostScript to produce landscape or portrait
calendars for any month and year.  The arguments {\bf month}, {\bf year},
and {\bf nmonths}, if provided, should be numeric.  The {\bf month} value
should be in the range 1 -- 12, and the {\bf year} value should be
specified as 1 or 2 digits or as the full 4 digit year.  If no numeric
arguments are provided, the calendar for the current month and year will
be generated.

If one numeric argument is provided, it is interpreted as the {\bf year}
value, and calendars for the entire year will be generated.  Otherwise,
{\bf nmonths} months, starting with {\bf month} and {\bf year}, will be
generated.

For whole-year calendars ({\it i.e.} the {\bf --w} option is given), the
command line arguments are interpreted somewhat differently.  By default,
all months in the current year are printed, starting with January.  If
the {\bf month} argument alone is given, it is expected to be the desired
{\bf year} to print, and prints all of the months in the given year.  If
both {\bf month} and {\bf year} are given, then 12 consecutive months are
printed starting at the given month and year.  If the {\bf month}, {\bf
year}, and{\bf nmonths} arguments are all present, printing begins with
the given month and year and {\bf nmonths} months are printed, rounded up
to the nearest multiple of 12.

{\bf The Date File}

By default, {\it pcal} simply prints an empty calendar.  Its real power
is in its ability to place ``events'' in appropriate days on the
calendar, thus allowing the user to create personalized calendars.  This
is achieved through the use of the ``date file''.

The date file is named {\it .calendar} ({\it pcal.dat} under MS-DOS or
{\it calendar.dat} under VMS), or {\it calendar.} for compatibility with
older versions.  {\it Pcal} will look in several places for such a file.
First, if a file called {\it.calendar} exists in the caller's home
directory, it is used.  Next, if such a file exists in the directory
indicated by environment variable {\bf PCAL\_DIR} (or the current
directory if no such variable is defined), it is used.  Finally, the
directory where the {\it pcal} executable resides will be checked.  If no
date file is found, an empty calendar is printed.

If a date file is found, it will be searched for lines with leading dates
matching the requested month and year.  Any text following the dates
found will be printed on the calendar under the appropriate day of the
month.  Dates in the {\it calendar} file may be expressed in any of
several formats:

{\tt\nofill
      $<$ordinal$>$ $<$day\_spec$>$ in $<$month\_spec$>$[$\ast$] [$<$text$>$]
      $<$day\_spec$>$ $<$prep$>$ $<$date\_spec$>$[$\ast$] [$<$text$>$]
      $<$date\_spec$>$[$\ast$] [$<$text$>$]
\fill}

Where:

{\tt\nofill
      $<$month\_name$>$        := first 3+ characters of name of month, or "all"
      $<$month\_spec$>$        := $<$month\_name$>$, or "year"
      $<$day\_spec$>$          := first 3+ characters of name of weekday, "day",
                              "weekday", "workday", "holiday", "nonweekday",
                              "nonworkday", "nonholiday", "new\_moon",
                              "first\_quarter", "full\_moon", or "last\_quarter"
      $<$ordinal$>$           := any ordinal number ("1st", "2nd", {\it etc.}),
                              "first" $\ldots$ "fifth", "last", "odd", "even",
                              or "all"
      $<$prep$>$              := "before", "preceding", "after", "following",
                              "on\_or\_before" ("oob"), or "on\_or\_after" ("ooa")
      $<$sep$>$               := one or more non-numeric, non-space, non-'$\ast$' characters
      $<$month$>$             := a numeric month (1-12)
      $<$day$>$               := day of month (1-31)
      $<$year$>$              := a numeric year
\fill}

If the {\bf --A} option (American date formats, the default) is given:

{\tt\nofill
   $<$date\_spec$>$    := [$<$month\_name$>$ $<$day$>$ $|$ $<$month$>$$<$sep$>$$<$day$>$[$<$sep$>$$<$year$>$]]
\fill}

If the {\bf --E} option (European date formats) is given:

{\tt\nofill
   $<$date\_spec$>$    := [$<$day$>$ $<$month\_name$>$ $|$ $<$day$>$$<$sep$>$$<$month$>$[$<$sep$>$$<$year$>$]]
\fill}

{\it Pcal} also allows format specifiers in both the text and foot
strings (see the {\bf --L}, {\bf --C}, {\bf --R}, and {\bf --N} options
below); each will be replaced by a corresponding string as outlined in
the table below.  Most of these are derived from the ANSI C {\it
strftime()} function; the {\bf \%[louwMD]} and {\bf \%[o0+--]} format
specifiers are specific to {\it pcal}:

{\tt\nofill
      \%a       abbreviated weekday
      \%A       full weekday
      \%b       abbreviated month name
      \%B       full month name
      \%d       day of month (1-31)
      \%j       day of year (1-366)
      \%l       days left in year (0-365)
      \%m       month (1-12)
      \%U       week number (0-53)
      \%W       week number (0-53)
      \%u       week number (1-54)
      \%w       week number (1-54)
      \%y       year w/o century (00-99)
      \%Y       year w/century
      \%\%       "\%" character


      \%o       print number as ordinal
      \%0       print number with leading zeroes
      \%+       use following month or year
      \%-       use previous month or year
      \%\{+N\}[DWMY]    adjust date by +N days/weeks/months/years
      \%\{-N\}[DWMY]    adjust date by -N days/weeks/months/years
\fill}

The {\bf \%u} specifier considers the week containing 1/1 as week 1 and
the following logical Sunday (the first day of the week as printed; cf.
the {\bf --F} option below) as the start of week 2;  {\bf \%U} considers
the first logical Sunday as the first day of week 1.  {\bf \%w} and {\bf
\%W} behave like {\bf \%u} and {\bf \%U} respectively, but use the first
logical Monday instead.  Note that {\bf \%w} has a different meaning to
{\it strftime().}

The {\bf \%o} format specifier prints a number as an ordinal, with the
appropriate suffix (``st'', ``nd'', ``rd'', or ``th'' in English)
appended.  For example, {\bf \%od} prints the day of the month as
``1st'', ``2nd'', ``3rd'', {\it etc}.

Unlike {\it strftime()}, {\it pcal} defaults to printing numbers (except
{\bf \%y}) without leading zeroes.  If leading zeroes are desired, the
`0' prefix may be used.  For example, {\bf \%0j} prints the first day of
year as ``001''.

The {\bf \%+} and {\bf \%--} format specifiers direct {\it pcal} to
substitute the following/previous month/year in the following {\bf
[bBmyY]} specifier.  For example, {\bf \%+B} prints the name of the next
month.

The {\bf \%\{[+--]N\}[DWMY]} format specifiers do not print anything, but
instead adjust the working date by {\bf N} days ({\bf D}), weeks
({\bf W}), months ({\bf M}), or years ({\bf Y}).  Subsequent format
specifiers use the adjusted date instead of the current date.  For
example, {\bf \%+1M \%B \%Y} adjusts the date forward by one month and
then prints the resulting month and year (``January 1992'' in December,
1991);  {\bf \%--2W \%b \%d} adjusts the date backward by two weeks and
prints the resulting month and day (``Jul 26'' on August 9).

Such date adjustments are normally cumulative; for example, {\bf
\%+1Y\%--1D} adjusts the date forward by one year and then backward by
one day.  If {\bf \%D} or {\bf \%M} is specified alone (or if {\bf N} is
zero), {\it pcal} restores the original date.  Note that {\bf \%M} has a
different meaning to the {\it strftime()} function.

The ``Notes'' box (see below) uses the first of the current month as the
default date.  All foot strings use the first of the current month in
single-month mode and the first of the starting month in whole-year mode.

Examples:

{\tt\nofill
    last Monday in May$\ast$         Memorial Day Holiday
\par\vspace{1.0\baselineskip}
    all Fridays in Oct          Status Meeting, 11 AM
    first workday in all        \%-B progress report due
    all Fri in all              Time card due, 3 PM
    all Monday in all           Fiscal week \%0W
    -2nd workday in all         Schedule for \%+B due \%+2D
    2nd full\_moon in all        $\,$Blue Moon
    Fri on\_or\_before all 15     $\;$Pay Day
    even Fridays in year        Pay Day
    183rd day of year           Mid-year (\%l days left)
\par\vspace{1.0\baselineskip}
    Tue after first Mon in Nov  Election Day (USA)
\par\vspace{1.0\baselineskip}
    4th Thu in Nov$\ast$             Thanksgiving
    Fri after 4th Thu in Nov$\ast$   Day after Thanksgiving
\par\vspace{1.0\baselineskip}
    12/25/90$\ast$                   Christmas     \# American
    25.12.90$\ast$                   Christmas     \# European
\par\vspace{1.0\baselineskip}
    Dec 25$\ast$                     Christmas     \# American
    25 Dec$\ast$                     Christmas     \# European
\fill}

Any non-numeric character may separate numeric dates.  Holidays may be
flagged by following the date immediately with `$\ast$' as in the
examples above; this will cause the date to be printed in gray.  ``Each''
and ``every'' are accepted as synonyms for ``all'', and any word may be
used in place of ``in''.  The abbreviations ``oob'' and ``ooa'' may be
used in place of the keywords ``on\_or\_before'' and ``on\_or\_after'',
respectively.  ``Nearest'' attempts to match the specified date; if that
fails, it tries the day after, then the day before, then two days after,
two days before, and so forth until a match occurs.

Wildcard day names are also provided.  The keyword ``weekday'' applies to
any days which are normally printed in black on the calendar.  The
keyword ``workday'' is the same, but does not include any holidays.  The
keyword ``holiday'' includes only those days flagged as holidays.  The
keywords ``nonweekday'', ``nonworkday'', and ``nonholiday'' are also
recognized as negations of the above.  See the {\bf CAVEATS} below for
important notes on using these keywords. Moon phases may also appear as
wildcards; ``nm'' is accepted as a synonym for ``new\_moon'', ``1q'' and
``fq'' for ``first\_quarter'', ``fm'' for ``full\_moon'', ``3q'' for
``third\_quarter'', and ``lq'' for ``last\_quarter''.

Ordinal day numbers may be used to specify dates, either relative to the
month or to the year.  Either words or numeric abbreviations may be used
for ``first'' through ``fifth''; higher numbers must be given using the
numeric equivalent ({\it e.g.} 100th).  Negative ordinal numbers may even be
used.  For example, ``--2nd'' means ``next to last''.

``Odd'' and ``even'' do not refer to the actual date; instead, ``odd''
means ``alternate, starting with the first'', and ``even'' means
``alternate, starting with the second''.  Thus, ``odd Fridays in March''
refers to the first, third, and (if present) fifth Fridays in March - not
to those Fridays falling on odd dates.

``All'' refers to each individual month; ``year'' refers to the year as
an entity.  Thus ``odd Fridays in all'' refers to the first, third, and
fifth Friday of each month, while ``odd Fridays in year'' refers to the
first Friday of January and every other Friday thereafter.

Text in the date file may use C-like escape sequences ({\it i.e.} a `\bs '
followed by a character, 1 -- 3 octal digits, or `x' followed by 1 -- 2
hexadecimal digits).  Escaped whitespace (including {\bf newline} ) and
the standard ANSI character escapes (`\bs a', `\bs b', `\bs f', `\bs n',
`\bs r', `\bs t', `\bs v') are all replaced by a single blank.

Lines in the {\it .calendar} file consisting of {\bf year \#\#\#\#} (where
{\bf \#\#\#\#} is a numeric year) can be used to set the year for
following entries.  This assumes that the following entries do not
contain a year; any date entries containing year information will set the
remembered year to that year.

Lines in the {\it .calendar} file consisting of {\bf opt $<$options$>$}
can be used to override the defaults for any command-line options except
{\bf --c}, {\bf --e}, {\bf --f}, {\bf --h}, {\bf --u}, {\bf --v}, {\bf
--D}, and {\bf --U}.  Any options specified in this manner are, in turn,
overridden by those specified explicitly on the command line.

Lines in the {\it .calendar} file consisting of {\bf note[/$<$number$>$]
$<$month$>$} can be used to place notes regarding the entire month in one
of the unused blocks of the calendar.  The {\bf $<$month$>$} indicator
may be either a number 1 through 12 or an alphabetic month name as
described above;  ``note all'' will place the associated text in the
notes block for each month in the current year.  {\bf $<$number$>$} is an
optional positive or negative number specifying the empty box where the
associated text is to be placed.  If positive, {\it pcal} counts forward
from the first empty box; if negative, {\it pcal} counts backward from
the last empty box.  Thus, {\bf ``note/1''} places the associated text in
the first empty box;  {\bf note/-3} in the third-to-last.  The default is
-1 if no $<$number$>$ is given (last empty box, immediately preceding the
small calendars on the bottom row; {\it cf.} {\bf --S}, {\bf --k}, and
{\bf --K}, below).

Comments are supported in the {\it .calendar} file.  Any characters
following a `\#' character through the end of the line are ignored.

{\it Pcal} supports rudimentary {\it cpp} -like functionality in the date
file, allowing the following constructs:  {\bf define $|$ undef}, {\bf
if\{\{n\}def\} $\ldots$ elif $\ldots$ $\ast$ else $\ldots$ endif,} and
{\bf include}.  Note that these are not preceded by `\#' as they are in
C.  Symbol names defined using these keywords (or via the {\bf --D}
option) are case-insensitive.  It is not an error to {\bf undef} an
undefined symbol, nor to {\bf define} a previously-defined one.  An {\bf
ifdef} alone is always {\bf false}; an {\bf ifndef} alone is always {\bf
true}.  {\bf if} is accepted as a synonym for {\bf ifdef}.

The name of the file in the {\bf include} directive may optionally be
surrounded by either ``'' or $<$$>$, both of which are ignored.  If the
name is not an absolute path, it is taken to be relative to the directory
where the file containing the directive is located.  {\it Pcal} is smart
enough to translate {\bf \~{}/} to the user's home directory.

In addition to pre-processing keywords, {\it pcal} also accepts boolean
expressions in {\bf if\{\{n\}def\}} and {\bf elif} directives.  These
expressions consist of symbol names joined by the boolean operators {\bf
!}, {\bf \&}, {\bf \^{}}, and {\bf $|$}, in order of precedence, high to
low.  Parentheses may be used to alter the precedence.  The synonyms {\bf
\&\&} and {\bf $|$$|$} are accepted for {\bf \&} and {\bf $|$}.  A symbol
name evaluates to {\bf true} if currently defined, {\bf false} if not;
thus:

{\tt\nofill
      ifdef A $|$ B $|$ C
\fill}

$\ldots$ is {\bf true} if any of the symbols A, B, and C is defined, and:

{\tt\nofill
      ifdef A \& B \& C
\fill}

$\ldots$ is {\bf true} if they all are.  Note that {\bf ifndef
$<$expr$>$} is equivalent to {\bf ifdef !( $<$expr$>$ ).}

{\bf The Moon File}

If a file of the name {\it .moon\#\#} ({\it moon\#\#.dat} under MS-DOS
and VMS), where {\bf \#\#} is the last two digits of the calendar year,
exists in the same directory as the date file (or in the directory where
{\it pcal} resides), uses the information contained within to calculate
the phase of the moon.  If no such file exists, {\it pcal} uses an
approximate algorithm.

Entries in the moon file must conform to the following syntax:

If the {\bf --A} option (American date formats, the default) is given:

{\tt\nofill
      $<$quarter$>$ $<$month$>$$<$sep$>$$<$day$>$ [$<$hour$>$$<$sep$>$$<$min$>$]
\fill}

If the {\bf --E} option (European date formats) is given:

{\tt\nofill
      $<$quarter$>$ $<$day$>$$<$sep$>$$<$month$>$ [$<$hour$>$$<$sep$>$$<$min$>$]
\fill}

Where:

{\tt\nofill
      $<$quarter$>$           := "nm", "fq" or "1q", "fm", "3q" or "lq"
                              (new moon, first quarter, full moon, last quarter)
      $<$hour$>$              := number 0-23 (24-hour clock)
      $<$min$>$               := number 0-59
\fill}

This file must contain entries for all quarter moons in the year, in
chronological order; if any errors are encountered, {\it pcal} will
revert to using its default algorithm.

As in the date file, comments start with `\#' and run through the end of
the given line.

{\bf Options}
{\it Pcal} has many options:
\begin{TPlist}{{\bf --n}{\it text\_font}[{\bf /}{\it size}]}
\item[{{\bf --e}}]
Prints an empty calendar.  Do not print entries from a {\it .calendar}
file.
\item[{{\bf --f} {\it cal}}]
Directs {\it pcal} to use the file name {\it cal} as the input file in
place of the default {\it .calendar} file.  Note that the search rules are
different when {\bf --f} is used.  If {\it cal} is an absolute file name
({\it i.e.}, starting with a `/'), then {\it pcal} attempts to open only
that file.  Otherwise, {\it pcal} looks for {\it cal} in the current
directory, then in the directory indicated by the environment variable
{\bf PCAL\_DIR} (if defined), and finally in the directory where the {\it
pcal} executable resides.  If the given {\it cal} file is not found, an
error results.
\item[{{\bf --o} {\it file}}]
Directs {\it pcal} to write the output to {\it file} instead of to
stdout.
\item[{{\bf --l}}]
Causes the output to be in landscape mode (default).  This also resets
the x- and y-axis scaling and translation factors to the defaults for
landscape mode.
\item[{{\bf --p}}]
Causes the output to be in portrait mode.  This also resets the x- and
y-axis scaling and translation factors to the defaults for portrait mode.
\item[{{\bf --j}}]
Causes the Julian date (day of year) to be printed in each calendar box.
\item[{{\bf --J}}]
Causes the Julian date and the number of days remaining in the year to be
printed in each calendar box.
\item[{{\bf --m}}]
Causes moon icons to be printed on dates corresponding to new, half, and
full moons (the default is that no moons are printed).
\item[{{\bf --M}}]
Causes moon icons to be printed on all dates (the default is that no
moons are printed).
\item[{{\bf --b} {\it day} {\bf $|$ all}}]
Causes all dates falling on weekday {\it day} to be printed in black;
{\bf --b all} causes all weekdays to be printed in black.
\item[{{\bf --g} {\it day} {\bf $|$ all}}]
Causes all dates falling on weekday {\it day} to be printed in gray;
{\bf --g all} causes all weekdays to be printed in gray.
\begin{IPlist}
\IPitem{{}}
The default for the {\bf --b} and {\bf --g} options is to print Saturdays
and Sundays in gray and other days, unless flagged as holidays, in black.
\end{IPlist}
\item[{{\bf --O}}]
Causes ``gray'' dates to be printed as outlined characters.
\item[{{\bf --G}}]
Causes ``gray'' dates to be printed as outlined characters filled with
gray.
\item[{{\bf --s} [{\it {date}]/[{fill}]}}]
Overrides the default values for date and/or fill box shading.  These
values must be in the range 0.0 (black) through 1.0 (white); they may be
set independently of each other.  The default values are 0.8 for dates
and 0.9 for empty boxes.
\item[{{\bf --F} {\it day}}]
Selects weekday {\it day} as the first day of the week.  The given day
will appear in the left-most column of the calendar.
\item[{{\bf --A}}]
Directs {\it pcal} to use American date conventions {\bf mm/dd[/yy]}
and {\bf month dd} when parsing the date file (default).
\item[{{\bf --E}}]
Directs {\it pcal} to use European date conventions {\bf dd/mm[/yy]}
and {\bf dd month} when parsing the date file.
\item[{{\bf --X} {\it xtrans}}]
Specifies the x-axis translation value for positioning the output on the
page.
\item[{{\bf --Y} {\it ytrans}}]
Specifies the y-axis translation value for positioning the output on the
page.
\item[{{\bf --x} {\it xscale}}]
Specifies the x-axis scaling factor for the calendar size.
\item[{{\bf --y} {\it yscale}}]
Specifies the y-axis scaling factor for the calendar size.
\item[{{\bf --t} {\it title\_font}}]
Specifies the name of a font to use to print the month name and year at
the top of the calendar, the foot strings, and the notes box heading.
For example, {\bf pcal --t Times-Roman}.
\item[{{\bf --d} {\it day\_font}}]
Similar to the {\bf --t} option, but selects the font used to print the
day numbers and weekday names.
\item[{{\bf --n} {\it text\_font} [{\bf /}{\it size}]}]
Similar to the {\bf --t} option, but selects the font used to print the
text inside each day and in the notes block.  The user may also select
the font size;  {\bf pcal --n Helvetica/8} sets the font to 8-point
Helvetica.
\item[{{\bf --D} {\it symbol}}]
Defines the named symbol prior to reading the date file.
\item[{{\bf --U} {\it symbol}}]
Un-defines the named symbol prior to reading the date file.
\item[{{\bf --L} {\it string}}]
Causes the accompanying string to be printed as a left-justified footer.
Format specifiers denoting the month and/or year may appear in the
string;  the appropriate values will be substituted upon printing.
\item[{{\bf --C} {\it string}}]
Similar to {\bf --L}, but causes the accompanying string to be printed as
a centered footer.
\item[{{\bf --R} {\it string}}]
Similar to {\bf --L}, but causes the accompanying string to be printed as
a right-justified footer.
\item[{{\bf --N} {\it string}}]
Causes the accompanying string to be printed as the heading for the
``Notes'' box.  Note, however, that {\it pcal} makes no attempt to ensure
that it fits.
\item[{{\bf --B}}]
Causes {\it pcal} to leave unused calendar boxes blank (default is gray).
\item[{{\bf --S}}]
Causes {\it pcal} to suppress printing the small calendars.  See the {\bf
CAVEATS} section for further details.
\item[{{\bf --k}}]
Causes {\it pcal} to print the small calendars in the upper left corner
(the default is to print them at the lower right).
\item[{{\bf --K}}]
Causes {\it pcal} to print the small calendar for the previous month in
the upper left corner and the next month in the lower right (the default
is to print both at the lower right).
\item[{{\bf --w}}]
Causes {\it pcal} to print a calendar for 12 consecutive months: 3 rows /
4 columns in landscape mode, 4 rows / 3 columns in portrait mode.  See
the {\bf CAVEATS} section for details on the use of this option with
other options.
\item[{{\bf --c}}]
Causes {\it pcal} to generate a date file suitable for use as input to
the Un$\ast$x {\it calendar(1)} utility.  The normal PostScript output is
suppressed.
\item[{{\bf --I}}]
Resets all parameters to the program defaults.
\item[{{\bf --h}}]
Causes {\it pcal} to write version information, parameter usage message,
and full explanation of options and file formats (to {\it stdout}) and
terminate.
\item[{{\bf --u}}]
Causes {\it pcal} to write version information and parameter usage
message (to {\it stdout}) and terminate.
\item[{{\bf --v}}]
Causes {\it pcal} to write version information only (to {\it stdout}) and
terminate.
\end{TPlist}

Any option which normally takes an argument may be specified without the
argument in order to reset the value to the program default.  Note that
while the {\bf --D} option alone clears all the defined symbols, the {\bf
--U} option alone has no effect.  The {\bf --} (or {\bf --\,--} as per
System V) argument may be used to disambiguate command lines such as:
\begin{IPlist}
\IPitem{{}}
{\bf pcal --t 9 90}
\end{IPlist}

This could be written instead as one of the following:
\begin{IPlist}
\IPitem{{}}
{\bf pcal --t -- 9 90}
\nwl
{\bf pcal --t --\,-- 9 90}
\end{IPlist}

If the environment variable {\bf PCAL\_OPTS} is defined, its contents are
parsed as a command line.  Flags set via {\bf PCAL\_OPTS} override the
program defaults, but are overridden by options set via {\bf opt} lines
in the {\it .calendar} file or explicitly on the command line.

\shead{CAVEATS}
The ``workday'' and ``holiday'' keywords are aware of only those holidays
which have already been flagged at the point where they appear.  For
example, consider January 1990:

{\tt\nofill
                                January 1990
                             S  M Tu  W Th  F  S
                                1  2  3  4  5  6
                             7  8  9 10 11 12 13
                            14 15 16 17 18 19 20
                            21 22 23 24 25 26 27
                            28 29 30 31
\fill}

If the {\it .calendar} file looked like this:

{\tt\nofill
      workday on\_or\_before all 15   payday
      3rd Mon in Jan$\ast$              $\;$MLK day
\fill}

$\ldots$ then {\it pcal} would mark the 15th as ``payday'' since at that
point in the {\it .calendar} file it has no way of knowing that January
15th will later be flagged as a holiday.  If the two lines were reversed,
such that the holiday preceded the ``workday'' wildcard, then {\it pcal}
would work as intended, marking instead the 12th as ``payday''.  Also,
beware of year boundaries which affect the handling of all of the day
wildcard keywords.  In general, it is best to place monthly wildcards
such as the example above at the end of each year to achieve the desired
effect.

When the {\bf --w} and {\bf --p} options are used together, {\it pcal}
revises the y-scale factor in order to use the entire portrait page;
therefore, the user should avoid using use the {\bf --y} option when
using both the {\bf --w} and {\bf --p} options.  Use of the {\bf --w}
option in any case effectively disables the {\bf --m}, {\bf --M}, {\bf
--j}, and {\bf --J} options.

The output of the {\bf --c} option may be used as input to subsequent
runs of {\it pcal}.  Note, however, that {\bf opt} lines (except for an
automatic {\bf opt --[A$|$E]}), comments, ``note'' text, and {\bf
ifdef}'d-out source will be lost.

The {\bf --S} option interacts with {\bf note[/$<$number$>$]};  if
used, it should be specified either on the command line or prior to the
first {\bf note} line in the date file.

\shead{SEE ALSO}
cal(1), calendar(1).

\shead{VERSION}
This documentation corresponds to v4.3 dated 13--Dec--1991 and was
\TeX{}set by Rick Dyson from the official troff man pages.

\shead{AUTHORS}
The original PostScript code to generate the calendars was written by
Patrick Wood (Copyright (c) 1987 by Patrick Wood of Pipeline Associates,
Inc.), and authorized for modification and redistribution.  The calendar
file inclusion code was originally written in {\it bs} (1) by Bill Vogel
of AT\&T.  Patrick's original PostScript was modified and enhanced
several times by others whose names have regrettably been lost.  Ken
Keirnan of Pacific Bell assembled the original ``C'' version upon which
this is based; additional modifications and enhancements are the work of
Joseph P. Larson, Ed Hand, Andrew W. Rogers, Mark Kantrowitz, Joe
Brownlee, Jamie Zawinski, Richard L. Dyson, Bill Hogsett, Floyd Miller,
Andy Fyfe, and Geoff Kuenning.
\end{document}
